Wire up PostHog + Segment analytics on the docs site#194
Merged
Conversation
Adds the Mintlify PostHog integration pointed at our existing Cloudflare Worker reverse proxy (api-posthog-worker.t49.workers.dev), matching how app.terminal49.com already ships events. Using the proxy host bypasses adblockers and keeps docs traffic in the same Production App+Website project (18843) as the main app and marketing site. Currently PostHog sees ~0 events from terminal49.com/docs because the Mintlify site never loaded the snippet. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Target branch is in the excluded branches list. |
dodeja
changed the title
dodeja
added a commit
that referenced
this pull request
Apr 11, 2026
Uses the same Segment write key that terminal49.com (marketing) and app.terminal49.com (Ember app) already use, so docs events land in the shared Segment source alongside marketing and app traffic. Follow-up to #194, which wired up PostHog but landed before the Segment commit could be reviewed. Note: Mintlify's Segment integration has no apiHost/proxy option, so docs events will hit cdn.segment.com / api.segment.io directly rather than routing through the cdn-segment-worker / api-segment-worker Cloudflare Workers that the Ember app and marketing site use. Not a blocker for landing — a meaningful fraction of docs events will still reach Segment; adblock-proofing can come later if Mintlify ships apiHost support. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
8 tasks
dodeja
added a commit
that referenced
this pull request
Apr 11, 2026
Adds `docs/segment.js`, which Mintlify auto-includes on every page, instead of using the built-in `integrations.segment` config. This lets us route the CDN and ingest hosts through our Cloudflare Worker reverse proxies — matching how app.terminal49.com and terminal49.com already ship Segment — so adblockers don't drop events. - CDN: cdn-segment-worker.t49.workers.dev -> cdn.segment.com - API: api-segment-worker.t49.workers.dev/v1 -> api.segment.io/v1 Mintlify's built-in Segment integration only takes a write key and loads directly from cdn.segment.com / api.segment.io, with no way to point at a proxy host. Custom scripts (docs: https://www.mintlify.com/docs/customize/custom-scripts) are the documented escape hatch. Also patches history.pushState / replaceState + listens to popstate so analytics.page() fires on every SPA route change (Mintlify is a SPA; analytics.js v1 doesn't auto-track client-side navigation). Follow-up to #194 (PostHog) and replaces the earlier version of this PR that used the built-in integration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
dodeja
added a commit
that referenced
this pull request
Apr 12, 2026
* Add Segment analytics via custom script (proxied through CF Workers) Adds `docs/segment.js`, which Mintlify auto-includes on every page, instead of using the built-in `integrations.segment` config. This lets us route the CDN and ingest hosts through our Cloudflare Worker reverse proxies — matching how app.terminal49.com and terminal49.com already ship Segment — so adblockers don't drop events. - CDN: cdn-segment-worker.t49.workers.dev -> cdn.segment.com - API: api-segment-worker.t49.workers.dev/v1 -> api.segment.io/v1 Mintlify's built-in Segment integration only takes a write key and loads directly from cdn.segment.com / api.segment.io, with no way to point at a proxy host. Custom scripts (docs: https://www.mintlify.com/docs/customize/custom-scripts) are the documented escape hatch. Also patches history.pushState / replaceState + listens to popstate so analytics.page() fires on every SPA route change (Mintlify is a SPA; analytics.js v1 doesn't auto-track client-side navigation). Follow-up to #194 (PostHog) and replaces the earlier version of this PR that used the built-in integration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Update Segment snippet to official v5.2.1 with proxy hosts Upgrades from the old v4.15.3 snippet (copied from the website repo) to the current official v5.2.1 from: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript/quickstart Key changes in v5.2.1: - `register` and `screen` methods added to the stub list - `data-global-segment-analytics-key` attribute on script tag - Buffered page context (bpc) captures canonical URL, pathname, title, referrer when queuing calls (important for SPA correctness) - Stale-reference guard when analytics is already initialized Still routes through our Cloudflare Workers for adblocker bypass: - CDN: cdn-segment-worker.t49.workers.dev - API: api-segment-worker.t49.workers.dev/v1 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/docs.jsonapiHostat our existing Cloudflare Worker reverse proxy (api-posthog-worker.t49.workers.dev), matching howapp.terminal49.comalready ships events (seeapps/tnt-ui/app/initializers/metrics.js). Samephc_l2ad…project key as the main app → docs traffic lands in the Production App+Website project (18843), alongside marketing + app events.QGH9…L7j2) that bothterminal49.com(marketing, Next.js) andapp.terminal49.com(Ember) already use, so docs events flow into the shared Segment source.Why
Today PostHog sees 0 pageviews for
terminal49.com/docs*in the last 30 days because the Mintlify site never loaded either snippet. The only/docs-adjacent traffic in PostHog is 23 legacy/api-docs*hits from the Ember marketing-site redirects, which isn't real docs traffic.Wiring both up lets us study:
Why the PostHog proxy host (not
us.i.posthog.com)The Worker is a transparent proxy — it rewrites
Hosttous.i.posthog.comand forwards the request (src/index.js). It has no origin allowlist, so CORS is whatever PostHog upstream returns (permissive). Using the proxy bypasses adblockers — standard PostHog SOP — and keeps parity withapp.terminal49.com.Known limitation: Segment proxy parity
Mintlify's Segment integration config only accepts
key— there's no way to point it at ourcdn-segment-worker/api-segment-workerWorkers. So docs Segment calls will hitcdn.segment.com/api.segment.iodirectly, and adblockers will drop some fraction. PostHog stays adblock-proof via the Worker either way. Not a blocker for landing this, but worth logging as future work.Test plan
terminal49.com/docsin a private window, click around a few pages$host = 'terminal49.com'AND$pathname LIKE '/docs%'— should see pageviews within a few minutes🤖 Generated with Claude Code